DimensionElementInsertDirect Function: Syntax & Use

DimensionElementInsertDirect in TM1 works exactly the same way as DimensionElementInsert except that it inserts the element immediately into the target dimension, rather than batching up all the new elements and doing it at the end of the step in the Turbo Integrator process.

Comparison to DimensionElementInsert

When compared to the default TM1 method, DimensionElementInsert, the DimensionElementInsertDirect function inserts the new element immediately, rather than waiting until the end fo the step in the TI process. When DimensionElementInsert is used, a copy is made of the entire dimension, the changes made and then once the step of the process is complete, the dimension is overwritten with the edits at the end of the Metadata step.

Syntax of DimensionElementInsertDirect

The syntax is:

DimensionElementInsertDirect(Dimension, InsertionPoint, ElName, ElType);

where:

• Dimension refers to the dimension to which you want to add a new element.
• InsertionPoint is an existing dimension element. The element being added to the dimension will be inserted immediately before this existing element. Note, if this parameter is empty, the new element is added to the end of the dimension.
• ElName is the name you want to assign to the new element.
• ElType is the element type. There are three possible ElType values, namley:
  • N – for a numeric element.
  • S – for a string element.
  • C – for a consolidated element.

Use Cases for DimensionElementInsertDirect

There are a couple of specific use cases for using DimensionElementInsertDirect rather than the traditional DimensionElementInsert. They involve the following:

1. When you have a large dimension and a small change to make, it might be considerably faster to have the dimension updated on the fly, rather than the traditional method of copying the dimension, modifying it and rewriting it.
2. When there is a large volume of source data, having the query run once only on the Data tab avoids running the query twice – once for the MetaData tab and a second time for the Data tab. Obviously to do this, the Metadata tab needs to be kept completely empty so that it is skipped.
3. It is also often used with DimensionElementComponentAddDirect to immediately update a consolidation structure. This will ensure your rollups are up to date before any additional changes are made.

Attribute Updates

Another advantage of using DimensionElementInsertDirect on the Data tab is for updating attributes. As the new element will be added directly to the dimension, we can follow it with attribute manipulation functions like AttrPutS or AttrPutN.

Notes

This function is different from DimensionElementInsert in that DimensionElementInsert will wait until the step of the TI (Prolog, Metadata, Data or Prolog) is complete before inserting all new elements in batch. The DimensionElementInsert can be much faster because of this.

Do You Need Help with Your TI?

If you need some help understanding how to get your elements into your dimension and assign attributes before you load data, give us a yell. We’d be more than happy to help with some advice.